The RTFHelp tagging language =========== The BMC tag =========== Purpose: to include a Windows bitmap in a help file Usage: optional Effect: the bitmap file following will be included at the current character position mSoft req: NA RTFHelp req: none syntax: BMC pyramid.bmp notes: You should place a fully-qualified path for the bitmap file in the BITMAPS section of your .HPJ file as shown below [BITMAPS] e:\rtf\pyramid.bmp ============ The BOLD tag ============ Purpose: to begin a line of bold text Usage: optional Effect: the text following the BOLD tag will be highlighted on the current topic screen mSoft req: NA RTFHelp req: none syntax: BOLD This is BOLD TEXT notes: The BOLD tag only applies to the line of text to its right. To force a space at the beginning of a line of BOLD text, use the SPACECHAR character (default: %). =========== The BOX tag =========== Purpose: to highlight text Usage: optional Effect: the current paragraph is boxed mSoft req: NA RTFHelp req: none syntax: BOX notes: Note that all paragraphs from this point on will be boxed as the boxed attribute is inherited from the previous group. Use the PARD (see) keyword to see the following paragraph to the default paragraph options, which do not include boxing. You will need to reset any options that are not the default. ================= The BROWSESEQ tag ================= Purpose: to permit users to move through related topics by clicking on the browse forward and backward buttons, it marks the current topic as being browseable Usage: optional Effect: Marks the topic as browsable mSoft req: each BROWSESEQ has three parts: a sequence name, a colon, and a sequence number. Each topic can is only permitted one BROWSESEQ. The help compiler will ignore the second plus BROWSESEQs placed in a single topic and you will be warned of this. Note that with the Windows 3.1 help compiler, you must add BrowseButtons() to the [CONFIG] section of your help project file. RTFHelp req: syntax: BROWSESEQ commands:005 notes: The sequence name relates this topic to all other topics having a BROWSESEQ with this name, the sequence number isn't really a number -- it's a string. Use strings like 005, 010 so you have room to add more later The help compiler will order the browse sequence name by sequence number (lowest to highest). The PHYSICAL ORDER of the individual BROWSESEQ statements is ignored. As noted above, the 'browse number' is a string and "50" will sort before "6" so use numbers with an equal number of digits like 005 and 100. ============== The CENTER tag ============== See 'RIGHT' =============== The DEFFONT tag =============== Purpose: to assign a new default font Usage: optional Effect: this tag is used to mark the font whose table ID is given as the default font mSoft req: NA RTFHelp req: none syntax: DEFFONT fontid where font id is the id given in the table above, e.g. 0 for Times New Roman. notes: none =================== The DEFINELINK tag =================== Purpose: to unambiguously identify the topic a link is to be resolved to (what topic should become the active topic when a link is clicked on) Usage: optional Effect: Marks the topic as the target of a link (it may be jumped to) mSoft req: the term following the DEFINELINK tag is limited to 255 characters RTFHelp req: DEFINELINKs are not case-sensitive Each instance of an DEFINELINK tag must be unique (although it can have multiple XREFID (see) tags that link to it) to the help file. At least one XREFID tag must exist for this link (via an PUTLINK) You may only have one DEFINELINK per topic, as the help compiler ignores any more you build. PUTLINK Printing XREFID LINKTO_PRINTING syntax: DEFINELINK LINKTO_PRINTING notes: The text on lines following the DEFINELINK will be displayed by HELP when the link is activated. N.B. -- any lines in a topic before the DEFINELINK will not be visible during the link, but will be visible via Search, etc. So you can have only a subset of your topic text in your links if you like Earlier versions of RTFHelp used the LINKCONTEXT command in place of DEFINELINK. =================== The DEFINEPOPUP tag =================== Purpose: to identify the text to be popped-up. Usage: optional Effect: Places the definition of a term in the help file mSoft req: the term following the DEFINEPOPUP tag is limited to 255 characters RTFHelp req: DEFINEPOPUPs are not case-sensitive Each instance of an DEFINEPOPUP tag must be unique (although it can have multiple XREFID (see) tags that link to it) to the help file. At least one XREFID tag must exist for this link (via a PUTPOPUP) You can only have one DEFINEPOPUP per topic, and the XREFID must be the first tag in a topic (before a TITLE or any other text). NOTE: each definition is considered a separate topic, although it is never seen independent of its context PUTPOPUP XREFID PTR_DEF syntax: DEFINEPOPUP PTR_DEF this is a definition notes: RTFHelp generates a new page (i.e., topic) for the DEFINEPOPUP. The text on lines following the DEFINEPOPUP will be displayed by HELP when the definition is requested. The DEFINEPOPUP tag was known as the XREFCONTEXT tag in earlier versions of RTFHelp. ============== The DEFTAB tag ============== Purpose: to assign a new default tab spacing Usage: optional Effect: this tag changes the default tab width mSoft req: NA RTFHelp req: none syntax: DEFTAB 1440 notes: The numeric argument to deftab must be given in TWIPS (q.v.). This version of RTF does not support the concept of a tab table, tab stops will occur every 'n' TWIPS starting at 0. =================== The FIRSTINDENT tag =================== Purpose: to change the offset of the first line of a paragraph Usage: optional Effect: this tag changes the horizontal starting position of the first line in a paragraph. mSoft req: NA RTFHelp req: none syntax: FIRSTINDENT -720 notes: The numeric argument to FIRSTINDENT must be given in TWIPS (q.v.). The default value of FIRSTINDENT is 0 (i.e., use LEFTINDENT value). Note that FIRSTINDENT is added to LEFTINDENT to get the horizontal starting position of the first line. The argument is negative, if you wish to "hang" (move left) the first line. If you wish to have 1/2" - indented paragraphs, use FIRSTINDENT 720. ============ The FONT tag ============ Purpose: to change the current font to a new font Usage: optional Effect: this tag sets the current font to the font whose handle is given as fontID mSoft req: NA RTFHelp req: none syntax: FONT fontID where fontID is an ID from the font table notes: none ================ The FONTSIZE tag ================ Purpose: to change the size of the current font Usage: optional Effect: this tag changes the typesize (height) of the current font mSoft req: NA RTFHelp req: none syntax: FONTSIZE size where size is the font size in half-points notes: As size is given in half-points, FONT 12 gives you a 6 point (1/12") font NOTE: if you plan to do a lot of work with fonts in your help files, it is very strongly suggested that you get a font library for Windows such as True Type or Bitstream. Your font sizes otherwise are limited to the available fonts and sizes given with the retail version of Windows (see Tools, 16.3.2 for a list of fonts and their sizes). If you are running with Windows 3.1, then you have TrueType fonts which are also scalable and this step is unnecessary. ============== The ITALIC tag ============== Purpose: to begin a line of italic text Usage: optional Effect: the text following the ITALIC tag will be italicized mSoft req: NA RTFHelp req: none syntax: ITALIC This is ITALIC TEXT notes: The ITALIC tag only applies to the line of text to its right. Use the SPACECHAR character (default: %) if you wish to have initial space characters before the italic text ============ The KEEP tag ============ Purpose: to keep all lines of a paragraph together Usage: optional Effect: the lines of a paragraph will not be split (wrapped) mSoft req: NA RTFHelp req: none syntax: KEEP notes: none. ================ The KEEPNEXT tag ================ Purpose: to keep the current paragraph together with the following paragraph Usage: optional Effect: The KEEPNEXT statement creates a non-scrolling region at the top of the topic. All paragraphs up until the next PARD tag will be included in the non-scrolling region. mSoft req: NA RTFHelp req: none syntax: KEEPNEXT notes: The WinHelp function of KEEPNEXT is slightly different from the raw RTF meaning of this text. All lines not in the non-scrolling region will be in a scrollable window below the non-scrollable region. =============== The KEYWORD tag =============== Purpose: to assign one or more keywords to the current topic Usage: optional Effect: the text following the keyword tag will be shown in WinHelp's Search dialog box. mSoft req: keywords may not exceed 255 characters in length help searches for words in a keyword phrase individually keywords may not be formatted (as explained above) keywords are not case-sensitive keywords may not contain semi-colons RTFHelp req: none syntax: KEYWORD mykeyword KEYWORD one multiword keyword KEYWORD keyword1; keyword2 is multiword notes: RTFHelp automatically generates a new paragraph tag before the given keywords keyword text MAY contain spaces (i.e, may be phrases) multiple keywords may be defined on one line by separating them with semi-colon characters as shown in the third example multiple topics may have the same keyword, when this keyword is selected in Search all topics having this keyword will have their TITLEs displayed in the Search Topics found listbox If a topic containing a keyword does not have a title, it will be listed in the Search Topics found listbox as '>>Untitled Topic<<' ============ The LEFT tag ============ See 'RIGHT' ================== The LEFTINDENT tag ================== Purpose: to change the offset of the start of all lines of a paragraph Usage: optional Effect: this tag changes the horizontal starting position of all lines in a paragraph. mSoft req: NA RTFHelp req: none syntax: LEFTINDENT 1440 notes: The numeric argument to LEFTINDENT must be given in TWIPS (q.v.). LEFTINDENT is often used together with RIGHTINDENT to set margins. ============ The LINE tag ============ Purpose: to start a new line without ending the current paragraph Usage: optional Effect: starts a new line in the current paragraph (with current settings) mSoft req: NA RTFHelp req: none syntax: LINE notes: Included for completeness. This tag is used to force linebreaks without starting a new paragraph. ============ The PAGE tag ============ Purpose: to mark the beginning of a new page Usage: optional Effect: this tag is used to begin a new page, thus it also begins a new topic mSoft req: NA RTFHelp req: none syntax: PAGE notes: Do not place text immediately following the PAGE tag. Start the new page's text on the following line ============ The PARA tag ============ Purpose: to mark the end of a paragraph Usage: optional Effect: this tag may be used to form the text of a particular topic into multiple paragraphs It is recommended that topics consist of short paragraphs for purposes of readability. mSoft req: NA RTFHelp req: none syntax: PARA notes: Do not place text immediately following the PARA tag. Start the new paragraph's text on the following line ============ The PARD tag ============ Purpose: to reset the current paragraph to defaults Usage: optional Effect: the current paragraph settings will be reset to the default settings (left-aligned, 0 indents, no space before or after paragraph, no tab stops, no border) mSoft req: WinHelp and/or HC dependent, default settings are subject to change. RTFHelp req: none syntax: PARD notes: Without using PARD, the current paragraph settings will be based on the previous (if any) paragraph's settings. This is often what the author wants, but with certain settings (see BOX) this is probably not the case and PARD will turn off all non-default features. Microsoft Word, for example, generates the equivalent of our PARA followed by PARD for every paragraph. PARD generates LEFT, FIRSTINDENT 0, LEFTINDENT 0, RIGHTINDENT 0, SA 0, SB 0, no tab stops and no border ============= The PLAIN tag ============= Purpose: to reset the current paragraph to PLAIN settings Usage: optional Effect: the current paragraph settings will be reset to no bold, no italic, no smallcaps, font 0, font size 24 mSoft req: WinHelp and/or HC dependent, defaults are subject change. RTFHelp req: none syntax: PLAIN notes: none ============ The PUTLINK tag ============ Purpose: to create a 'link' in the current topic to another topic Usage: optional Effect: The user clicks on the link text to change the current topic in WinHelp to the topic that was linked to mSoft req: none RTFHelp req: Each instance of an PUTLINK tag must be followed by a new line containing an XREFID (see) and in the topic to be linked to a DEFINEPOPUP (see) must also be defined XREFID LINKTO_PRINTING DEFINEPOPUP LINKTO_PRINTING syntax: PUTLINK Printing notes: RTFHelp automatically generates a new paragraph for the PUTLINK (and also for its following XREFID). Earlier versions of RTFHelp used the XREF tag in place of the PUTLINK tag. ================== The PUTPOPUP tag ================== Purpose: to give further explanation about a word or phrase Usage: optional Effect: The user clicks the left mouse button on the word or phrase being defined and a pop-up topic will appear containing further information mSoft req: none RTFHelp req: Each instance of a PUTPOPUP tag must be followed by a new line containing an XREFID (see) and once per topic file an DEFINEPOPUP (see) must actually define the text that will appear in the Help box XREFID PTR_AARDVARK DEFINEPOPUP PTR_AARDVARK a burrowing African mammal that feeds on ants and termites syntax: PUTPOPUP aardvark notes: PUTPOPUP tags (definition topics in the Tools guide) are considered by RTFHelp to be a part of the previous paragraph. The PUTPOUP tag was known as the DEFINTION tag in earlier versions of RTFHelp. ============= The RIGHT tag ============= Purpose: to right align a paragraph Usage: optional Effect: the text on the lines following the tag will be right aligned until EOF, another marker (LEFT, CENTER) is used, or default properties are reset with the PARD tag. mSoft req: NA RTFHelp req: none syntax: RIGHT This text will be right aligned notes: The syntax for the LEFT, CENTER and JUST alignment commands is identical. RTFHelp generates a new PARA tag for each RIGHT, LEFT CENTER and JUST tag. =================== The RIGHTINDENT tag =================== Purpose: to change the offset of the end of all lines of a paragraph Usage: optional Effect: this tag changes the horizontal ending position of all lines in a paragraph. mSoft req: NA RTFHelp req: none syntax: RIGHTINDENT 1440 notes: The numeric argument to RIGHTINDENT must be given in TWIPS (q.v.). See LEFTINDENT for more information. ========== The SA tag ========== Purpose: to add vertical whitespace after a paragraph Usage: optional Effect: An amount of vertical whitespace (blank lines) will separate this paragraph from the following one mSoft req: NA RTFHelp req: none syntax: SA 720 notes: The argument is given in TWIPS. Note that all paragraphs from this point on will have the same SA value. You will need to explicitly reset SA if this is not your intention. The syntax for the SB and SL vertical spacing commands is identical. ========== The SB tag ========== Purpose: to place vertical whitespace before a paragraph Usage: optional Effect: An amount of vertical whitespace (blank lines) will separate this paragraph from the preceding one mSoft req: NA RTFHelp req: none syntax: SB 720 notes: The argument is given in TWIPS. See SA for other information. ========== The SL tag ========== Purpose: to place vertical whitespace between the lines of a paragraph Usage: optional Effect: The given amount of vertical whitespace (blank space) will separate the lines of this paragraph mSoft req: NA RTFHelp req: none syntax: SL 240 notes: The argument is given in TWIPS. See SA for other information. This tag is useful for enhancing the readability of your help text. ================= The SMALLCAPS tag ================= Purpose: to italicize text Usage: optional Effect: the text following the SMALLCAPS tag will be in small caps mSoft req: NA RTFHelp req: none syntax: SMALLCAPS This is in small caps notes: Only the text following the SMALLCAPS tag will be in smallcaps. Use the SPACECHAR character (default: %) to add leading space characters to your SMALLCAPS text. ================= The SPACECHAR tag ================= Purpose: to reset the default 'hardspace' character Usage: optional Effect: the single character following the SPACECHAR tag will become the hardspace character and may be used to force a space that will not be stripped off in line initial position for those tags that tag arguments such as BOLD and ITALIC. mSoft req: NA RTFHelp req: none syntax: SPACECHAR % BOLD %%%This line has three initial spaces. notes: The SPACECHAR character is only valid as the first non-space character(s) on a line of text. Another option (instead of this tag) would be to modify the RTFHelp parser to take quoted strings to preserve spacing. Note that the SPACECHAR character is only necessary for tags taking arguments (such as BOLD) to preserve leading space characters that would otherwise be stripped out by the parser. =========== The TAB tag =========== Purpose: to move the current character position to the next tab stop Usage: optional Effect: "tabs" the current character position over to the next tab stop based on DEFTAB mSoft req: NA RTFHelp req: none syntax: TAB notes: This is the TAB character (ASCII 9). ============= The TITLE tag ============= Purpose: to name the current topic Usage: optional Effect: the text following the title tag will be shown a) in the Bookmark menu b) in the Topics Found list of a keyword Search mSoft req: titles can be no longer than 128 characters (extra truncated) titles cannot be formatted (e.g., you cannot use BOLD within TITLE text) RTFHelp req: none syntax: TITLE This is the title of my topic notes: Note that the TITLE text does not appear in the topic itself. ========== The TX tag ========== Purpose: to set the position of a tab stop Usage: optional Effect: the tab stop is set based on the left margin, cleared on the next PARD statement mSoft req: NA RTFHelp req: none syntax: TX n notes: As above. The numeric argument to deftab must be given in TWIPS (q.v.). =========== The TQC tag =========== Purpose: to center text at the next tab stop Usage: optional Effect: text will be centered at the following tab stop mSoft req: NA RTFHelp req: none syntax: TQC notes: None. =========== The TQR tag =========== Purpose: to right-align text at the next tab stop Usage: optional Effect: text will be right-aligned at the following tab stop mSoft req: NA RTFHelp req: none syntax: TQR notes: None. ============== The XREFID tag ============== Purpose: to unambiguously identify a particular topic or definition in a help file that is to be linked to Usage: optional Effect: none (never used by itself) mSoft req: the term following the XREFID tag is limited to 255 characters RTFHelp req: XREFIDs are not case-sensitive Each instance of an XREFID tag must immediately follow the PUTLINK (see) or PUTPOPUP (see) tag it supports An DEFINEPOPUP (see) tag must also be written containing the identical string found in the XREFID PUTLINK Printing DEFINEPOPUP LINKTO_PRINTING syntax: XREFID LINKTO_PRINTING notes: RTFHelp does not generate a new paragraph for the XREFID. It is found in the same paragraph as its previous PUTPOPUP or PUTLINK ============== The * or ; tag ============== Purpose: to mark a comment Usage: optional Effect: the text following the comment tag will not be placed in the RTFHelp file to be generated it is for RTFHelp user informational purposes only mSoft req: NA RTFHelp req: Must begin in column 1 of a line syntax: ; This is a comment * This is also a comment notes: Unformatted text cannot have a '*' or ';' in column 1 or the text will be considered a comment by RTFHelp and will not be generated into the help file. Place the '*' or ';' in column 2 or later.